package com.srmt.document.api;

import com.srmt.document.model.RowData;
import com.srmt.document.model.ColumnData;
import com.srmt.document.table.model.TableType;
import com.srmt.document.exception.ContentException;
import com.srmt.document.exception.TableException;
import com.srmt.document.exception.CellException;
import com.srmt.feishu.client.model.ProtectedDimension;
import java.util.List;

/**
 * 内容写入接口
 * 提供文档内容的各种写入操作
 * 
 * @author YourCompany
 * @since 1.0.0
 */
public interface ContentWriter {
    
    // ============ 文本操作 ============
    
    /**
     * 在指定文字内容后增加字符串
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，用于定位插入位置
     * @param text 要添加的文字
     * @throws ContentException 操作失败时抛出
     */
    void appendTextAfter(String docId, String anchorText, String text) throws ContentException;
    
    /**
     * 在指定文字内容前增加字符串
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，用于定位插入位置
     * @param text 要添加的文字
     * @throws ContentException 操作失败时抛出
     */
    void insertTextBefore(String docId, String anchorText, String text) throws ContentException;
    
    /**
     * 替换指定文字内容
     * 
     * @param docId 文档ID
     * @param oldText 原文字
     * @param newText 新文字
     * @throws ContentException 操作失败时抛出
     */
    void replaceText(String docId, String oldText, String newText) throws ContentException;
    
    /**
     * 替换所有匹配的文字内容
     * 
     * @param docId 文档ID
     * @param oldText 原文字
     * @param newText 新文字
     * @return 替换的次数
     * @throws ContentException 操作失败时抛出
     */
    int replaceAllText(String docId, String oldText, String newText) throws ContentException;
    
    /**
     * 使用正则表达式替换匹配的文本内容
     * 
     * @param docId 文档ID
     * @param pattern 正则表达式模式
     * @param replacement 替换文本（支持捕获组引用如$1, $2）
     * @return 替换的次数
     * @throws ContentException 操作失败时抛出，包括正则表达式语法错误
     * @since 1.6.0
     */
    int replaceTextByPattern(String docId, String pattern, String replacement) throws ContentException;

    
    // ============ 表格创建 ============
    
    /**
     * 在指定位置创建表格（默认创建普通表格）
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，如果为null则在文档末尾创建
     * @param rows 行数
     * @param cols 列数
     * @param content 表格内容（可选），二维列表
     * @throws TableException 创建失败时抛出
     */
    void createTable(String docId, String anchorText, int rows, int cols, 
                    List<List<String>> content) throws TableException;
    
    /**
     * 在指定位置创建指定类型的表格
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，如果为null则在文档末尾创建
     * @param rows 行数
     * @param cols 列数
     * @param content 表格内容（可选），二维列表
     * @param tableType 表格类型（NORMAL或SHEET）
     * @throws TableException 创建失败时抛出
     * @since 5.0.0
     */
    void createTable(String docId, String anchorText, int rows, int cols, 
                    List<List<String>> content, TableType tableType) throws TableException;
    
    // ============ 表格操作 - 按行 ============
    
    /**
     * 在指定文字内容后的表格中添加行数据
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，用于定位表格
     * @param rows 要添加的行数据
     * @param startRow 开始行坐标（从1开始）
     * @throws TableException 操作失败时抛出
     */
    void addTableRowsAfter(String docId, String anchorText, List<RowData> rows, int startRow) 
            throws TableException;
    
    /**
     * 在指定文字内容后的表格中添加行数据（追加到末尾）
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，用于定位表格
     * @param rows 要添加的行数据
     * @throws TableException 操作失败时抛出
     */
    void appendTableRowsAfter(String docId, String anchorText, List<RowData> rows) 
            throws TableException;
    
    /**
     * 删除表格中的行
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param startRow 开始行（包含） >= 1
     * @param endRow 结束行（包含）   >= 1
     * @throws TableException 操作失败时抛出
     */
    void deleteTableRows(String docId, String tableAnchor, int startRow, int endRow) 
            throws TableException;
    
    // ============ 表格操作 - 按列 ============
    
    /**
     * 在指定文字内容后的表格中添加列数据
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，用于定位表格
     * @param columns 要添加的列数据
     * @param startColumn 开始列坐标（从0开始）
     * @throws TableException 操作失败时抛出
     */
    void addTableColumnsAfter(String docId, String anchorText, List<ColumnData> columns, int startColumn) 
            throws TableException;
    
    /**
     * 在指定文字内容后的表格中添加列数据（追加到末尾）
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字，用于定位表格
     * @param columns 要添加的列数据
     * @throws TableException 操作失败时抛出
     */
    void appendTableColumnsAfter(String docId, String anchorText, List<ColumnData> columns) 
            throws TableException;
    
    /**
     * 删除表格中的列
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param startColumn 开始列（包含） >=1
     * @param endColumn 结束列（包含）   >=1
     * @throws TableException 操作失败时抛出
     */
    void deleteTableColumns(String docId, String tableAnchor, int startColumn, int endColumn) 
            throws TableException;
    
    // ============ 单元格操作 ============
    
    /**
     * 设置单元格内容
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param row 行坐标（从1开始）
     * @param column 列坐标（从1开始）
     * @param value 单元格的值
     * @throws CellException 操作失败时抛出
     */
    void setCellContent(String docId, String tableAnchor, int row, int column, String value) 
            throws CellException;
    
    /**
     * 批量设置单元格内容
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param startRow 开始行 >= 1
     * @param startColumn 开始列 >= 1
     * @param values 二维数组的值
     * @throws CellException 操作失败时抛出
     */
    void setCellsContent(String docId, String tableAnchor, int startRow, int startColumn, 
                        List<List<String>> values) throws CellException;
    
    /**
     * 替换包含指定文字的合并单元格右侧相邻列的单元格内容
     * 
     * 该方法会查找表格中包含指定文字的合并单元格，然后替换该合并单元格
     * 右侧紧邻列中对应行的单元格内容。例如，如果合并单元格跨越第1-3行，
     * 则会替换其右侧列第1-3行的内容。
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字，用于定位表格
     * @param cellText 合并单元格中包含的文字，用于定位合并单元格
     * @param values 要替换的值列表，数量应与合并单元格跨越的行数一致
     * @throws CellException 操作失败时抛出
     */
    void replaceCellsNextToMergedCell(String docId, String tableAnchor, String cellText, List<String> values) 
            throws CellException;
    
    /**
     * 合并单元格
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param startRow 开始行 1-base
     * @param startColumn 开始列 1-base
     * @param endRow 结束行 1-base
     * @param endColumn 结束列 1-base
     * @throws CellException 操作失败时抛出
     */
    void mergeCells(String docId, String tableAnchor, int startRow, int startColumn, 
                   int endRow, int endColumn) throws CellException;
    
    // ============ 表格保护操作 ============
    
    /**
     * 添加表格保护范围
     * 该方法会通过锚点文字找到对应的电子表格（Sheet类型），然后设置保护范围
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字，用于定位电子表格
     * @param protectedDimensions 保护维度配置列表
     * @param userIdType 用户ID类型（open_id, union_id, user_id）
     * @throws TableException 操作失败时抛出
     * @since 5.1.0
     */
    void addProtectedDimension(String docId, String tableAnchor, 
                              List<ProtectedDimension> protectedDimensions,
                              String userIdType) throws TableException;
    
}